109 docs validate readme template structure in elastic package #2716
Conversation
cmd/build.go
Outdated
| err = docs.ValidateDocsStructure(packageRoot) | ||
| if err != nil { | ||
| return fmt.Errorf("validating docs structure failed: %w", err) | ||
| } |
There was a problem hiding this comment.
Should we do this after updating readmes below?
internal/docs/readme.go
Outdated
|
|
||
| func validateReadmeStructure(packageRoot string) (error) { | ||
| requiredHeaders := []string{"Overview", "Troubleshooting", "Scaling"} | ||
| fileName := "README.md" |
There was a problem hiding this comment.
There are packages with a main README.md, and multiple .md files, one for each policy template. An example of this is the AWS package. Do we want to apply the same validation in these cases?
There was a problem hiding this comment.
Do you know where those other .md files are used? And if they have the same type of content than the readme.md? If so, I think they should be validated too yes.
If was also wondering if we should validate the docs under _dev/build/docs or under build/docs instead as not all integrations have a _dev/build/docs/README. wdyt?
There was a problem hiding this comment.
Do you know where those other .md files are used?
The are used in packages that define multiple policy templates. They are used in the integrations UI, where each template appears as a different tile, as if it were a different package.
See for example the AWS package: https://github.com/elastic/integrations/tree/main/packages/aws/docs
And if they have the same type of content than the readme.md? If so, I think they should be validated too yes.
In principle they have the same type of content, yes.
If was also wondering if we should validate the docs under
_dev/build/docsor underbuild/docsinstead as not all integrations have a_dev/build/docs/README. wdyt?
We should validate the docs under the docs directory, that will be the files included in the package.
_dev/build/docs may contain templating and in principle doesn't need to be valid as final documentation.
| dependencies: | ||
| ecs: | ||
| reference: [email protected] | ||
| docs_structure_enforced: true |
There was a problem hiding this comment.
Maybe we can make this an object, so it doesn't need to be an all or nothing? This could allow for example to introduce some additional setting to force only a set of headers.
docs_structure_enforced:
enabled: true
skip:
- title: Performance and scaling
reason: System metrics, no performance tuning available.
| dependencies: | ||
| ecs: | ||
| reference: [email protected] | ||
| docs_structure_enforced: true |
There was a problem hiding this comment.
This setting should not be under dependencies.
It could also belong to the validation.yml file at the root of the package.
There was a problem hiding this comment.
it might make more sense indeed to have it as part of the validation.yml instead
💔 Build Failed
Failed CI StepsHistory
|
Changes in package-specs that need to occur before elastic/package-spec#924
Tests will fail until then.
Initial discussion on elastic-package
RFC
Goal
Enforce the structure of the docs (README.md) according to the template created by the docs team.
Implementation
The template will be enforced only on new integrations. When not set in
validation.ymlthedocs_structure_enforcedisfalseby default.The template will evolve with time, so we need to be able to handle versions.